package cn.com.nes.site.service.crm.opportunity;

import cn.com.nes.mybatis.agent.crm.entity.OpportunityAreaCode;
import cn.com.nes.site.service.crm.opportunity.bo.OpportunityAreaCodeBo;
import cn.com.nes.site.service.crm.opportunity.dto.OpportunityAreaCodeDTO;
import cn.com.nes.site.service.system.region.dto.RegionCodeTreeNode;
import com.baomidou.mybatisplus.extension.service.IService;

import java.util.List;

/**
 * @author yishuai
 */
public interface OpportunityAreaCodeService extends IService<OpportunityAreaCode> {

    void save(OpportunityAreaCodeBo opportunityAreaCodeBo) throws Exception;


    /**
     * 查询负责本行政区划的商机id列表
     */
    List<String> getOpportunityIdListByAreaCode(String areaCode);


    /**
     * @param opportunityUuid
     * @return
     */
    List<OpportunityAreaCodeDTO> getAreaCodesByOpportunityUuid(String opportunityUuid) throws Exception;


    /**
     * Retrieves a tree structure of region codes associated with a given opportunity.
     *
     * This method generates a hierarchical representation (tree) of region codes that are linked
     * to the specified opportunity UUID. Each node in the tree includes details about the region,
     * such as its geographic coordinates, full name, and level within the administrative hierarchy.
     *
     * @param opportunityUuid The unique identifier for the opportunity. This ID is crucial for identifying
     *                        the correct set of region codes tied to the opportunity.
     * @return A list of {@link RegionCodeTreeNode} objects, representing the hierarchical tree of region codes
     *         for the given opportunity. The tree structure allows traversal through the administrative
     *         divisions related to the opportunity.
     * @throws Exception If an exception occurs during the retrieval process, which could involve issues
     *                   with data access, invalid input parameters, or other unexpected errors.
     */
    List<RegionCodeTreeNode> getRegionCodeTreeForOpportunity(String opportunityUuid) throws Exception;


    /**
     * Retrieves a list of all coverage regions associated with a given opportunity.
     *
     * This method fetches a comprehensive list of region codes that fall under the specified opportunity's scope.
     * It provides a view of all administrative regions linked to the opportunity without any filters.
     *
     * @param opportunityUuid The unique identifier for the opportunity. This parameter is essential for identifying the correct opportunity record.
     *                        Must be a valid UUID string corresponding to an existing opportunity.
     * @return A list of strings, each representing a unique region code associated with the given opportunity.
     *         The list encompasses all coverage areas for the specified opportunity.
     * @throws Exception If an error occurs during the retrieval process, such as a database access failure or an invalid opportunity UUID.
     */
    List<String> getAllCoverRegionsForOpportunity(String opportunityUuid) throws Exception;


    /**
     * Retrieves a list of region code tree nodes associated with a given opportunity and an optional higher-level region code.
     *
     * This method constructs a hierarchical tree structure representing region codes linked to a specific opportunity.
     * It allows filtering these regions based on a higher-level region code to focus on a subset of the geographical hierarchy.
     *
     * @param opportunityUuid The unique identifier for the opportunity that the region codes must be related to.
     *                        Must not be null or empty.
     * @param higherRegionCode An optional code specifying a higher-level region to filter the results.
     *                         If provided, only regions within this higher-level region will be included.
     *                         Can be null to include all regions associated with the opportunity.
     * @return A list of {@link RegionCodeTreeNode} instances, each representing a region code with its hierarchical context.
     *         The tree nodes include details such as the region's full name, level, and geographical coordinates.
     * @throws Exception If there is an issue retrieving the data, such as a failure in accessing the underlying storage or invalid parameters.
     */
    List<RegionCodeTreeNode> getRegionCodesForOpportunity(String opportunityUuid, String higherRegionCode) throws Exception;

}
